home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000…tember: Reference Library / Dev.CD Sep 00 RL Disk 1.toast / mac / What's New / • What was new 08⁄00 / Sample Code / Interapplication Comm / MoreOSL / MoreAppleEvents / MoreAppleEvents.h < prev   
Encoding:
C/C++ Source or Header  |  2000-06-23  |  21.4 KB  |  546 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        MoreAppleEvents.h
  3.  
  4.     Contains:    
  5.  
  6.     Written by:    Pete Gontier
  7.  
  8.     Copyright:    Copyright (c) 1998 Apple Computer, Inc., All Rights Reserved.
  9.  
  10.                 You may incorporate this Apple sample source code into your program(s) without
  11.                 restriction. This Apple sample source code has been provided "AS IS" and the
  12.                 responsibility for its operation is yours. You are not permitted to redistribute
  13.                 this Apple sample source code as "Apple sample source code" after having made
  14.                 changes. If you're going to re-distribute the source, we require that you make
  15.                 it clear in the source that the code was descended from Apple sample source
  16.                 code, but that you've made changes.
  17.  
  18.     Change History (most recent first):
  19.  
  20.          <9>     27/3/00    Quinn   Remove MoreAEDeleteItemFromRecord.  It's functionality is
  21.                                     covered by AEDeleteKeyDesc.
  22.          <8>     20/3/00    Quinn   Added routines to deal with "missing value".  Added
  23.                                     MoreAECopyDescriptorDataToHandle.  Fixed some copy and paste
  24.                                     errors in the comments.
  25.          <7>      3/9/00    GW      Intergrating AppleEvent Helper code
  26.          <6>      6/3/00    Quinn   Added a bunch of trivial wrapper routines.  George may come
  27.                                     along and change all these soon, but I needed them for MoreOSL.
  28.          <5>      1/3/00    Quinn   Change the signature for AEGetDescData to match the version we
  29.                                     actually shipped.
  30.          <4>     2/15/99    PCG     add AEGetDescDataSize for non-Carbon clients
  31.          <3>     1/29/99    PCG     add AEGetDescData
  32.          <2>    11/11/98    PCG     fix headers
  33.          <1>    11/10/98    PCG     first big re-org at behest of Quinn
  34.  
  35.     Old Change History (most recent first):
  36.  
  37.          <4>    10/11/98    Quinn   Convert "MorePrefix.h" to "MoreSetup.h".
  38.          <3>      9/9/98    PCG     re-work import and export pragmas
  39.          <2>     7/24/98    PCG        coddle linker (C++, CFM-68K)
  40.          <1>     6/16/98    PCG     initial checkin
  41. */
  42.  
  43. #pragma once
  44.  
  45. //********************************************************************************
  46. //    A private conditionals file to setup the build environment for this project.
  47. #include "MoreSetup.h"
  48. //********************************************************************************
  49. //    System includes
  50. #include <AERegistry.h>
  51. #include <AEObjects.h>
  52. #include <AEPackObject.h>
  53. #include <EPPC.h>
  54. #include <Gestalt.h>
  55. #include <Processes.h>
  56. //********************************************************************************
  57. #define    kFlagNotSet    -1
  58. //********************************************************************************
  59. #ifdef __cplusplus
  60.     extern "C" {
  61. #endif
  62. /********************************************************************************
  63.     Create and return an AEDesc for the process target with the specified PSN.
  64.     If no PSN is supplied the use the current process
  65.  
  66.     pAEEventClass        input:    The class of the event to be created.
  67.     pAEEventID            input:    The ID of the event to be created.
  68.     pAppleEvent        input:    Pointer to an AppleEvent where the
  69.                             event record will be returned.
  70.                     output:    The Apple event.
  71.     
  72.     RESULT CODES
  73.     ____________
  74.     noErr               0    No error    
  75.     memFullErr        -108    Not enough room in heap zone    
  76.     ____________
  77. */
  78. extern pascal OSErr MoreAECreateProcessTarget (ProcessSerialNumber *pPSN, AEDesc *target);
  79. /********************************************************************************
  80.     Create and return an AppleEvent of the given class and ID. The event will be
  81.     targeted at the current process, with an AEAddressDesc of type
  82.     typeProcessSerialNumber.
  83.  
  84.     pAEEventClass        input:    The class of the event to be created.
  85.     pAEEventID            input:    The ID of the event to be created.
  86.     pAppleEvent        input:    Pointer to an AppleEvent where the
  87.                             event record will be returned.
  88.                     output:    The Apple event.
  89.     
  90.     RESULT CODES
  91.     ____________
  92.     noErr               0    No error    
  93.     memFullErr        -108    Not enough room in heap zone    
  94.     ____________
  95. */
  96. extern pascal OSErr MoreAECreateAppleEventSelfTarget( AEEventClass pAEEventClass,
  97.                               AEEventID pAEEventID,
  98.                               AppleEvent *pAppleEvent );
  99. /********************************************************************************
  100.     Create and return an AppleEvent of the given class and ID. The event will be
  101.     targeted at the process specified by the target type and creator codes, 
  102.     with an AEAddressDesc of type typeProcessSerialNumber.
  103.  
  104.     pType            input:    The file type of the process to be found.
  105.     pCreator        input:    The creator type of the process to be found.
  106.     pAEEventClass    input:    The class of the event to be created.
  107.     pAEEventID        input:    The ID of the event to be created.
  108.     pAppleEvent        input:    Pointer to an AppleEvent where the
  109.                             event record will be returned.
  110.                     output:    The Apple event.
  111.     
  112.     RESULT CODES
  113.     ____________
  114.     noErr               0    No error    
  115.     memFullErr        -108    Not enough room in heap zone    
  116.     procNotFound    –600    No eligible process with specified descriptor
  117.     ____________
  118. */
  119. extern pascal OSErr    MoreAECreateAppleEventSignatureTarget( OSType pType,
  120.                                              OSType pCreator,
  121.                                              AEEventClass pAEEventClass,
  122.                                              AEEventID pAEEventID,
  123.                                              AppleEvent *pAppleEvent );
  124. /********************************************************************************
  125.     Create and return an AppleEvent of the given class and ID. The event will be
  126.     targeted at the application with the specific creator.
  127.  
  128.     psnPtr            input:    Pointer to the PSN to target the event with.
  129.     pAEEventClass    input:    The class of the event to be created.
  130.     pAEEventID        input:    The ID of the event to be created.
  131.     pAppleEvent        input:    Pointer to an AppleEvent where the
  132.                             event record will be returned.
  133.                     output:    The Apple event.
  134.     
  135.     RESULT CODES
  136.     ____________
  137.     noErr               0    No error    
  138.     memFullErr        -108    Not enough room in heap zone    
  139.     procNotFound    –600    No eligible process with specified descriptor
  140.     ____________
  141. */
  142. pascal OSStatus MoreAECreateAppleEventCreatorTarget(
  143.                             const AEEventClass pAEEventClass,
  144.                             const AEEventID pAEEventID,
  145.                             const OSType pCreator,
  146.                             AppleEvent *pAppleEvent);
  147. /********************************************************************************
  148.     Create and return an AppleEvent of the given class and ID. The event will be
  149.     targeted with the provided PSN.
  150.  
  151.     psnPtr            input:    Pointer to the PSN to target the event with.
  152.     pAEEventClass    input:    The class of the event to be created.
  153.     pAEEventID        input:    The ID of the event to be created.
  154.     pAppleEvent        input:    Pointer to an AppleEvent where the
  155.                             event record will be returned.
  156.                     output:    The Apple event.
  157.     
  158.     RESULT CODES
  159.     ____________
  160.     noErr               0    No error    
  161.     memFullErr        -108    Not enough room in heap zone    
  162.     procNotFound    –600    No eligible process with specified descriptor
  163.     ____________
  164. */
  165. extern pascal OSErr    MoreAECreateAppleEventProcessTarget( const ProcessSerialNumberPtr psnPtr,
  166.                                            AEEventClass pAEEventClass,
  167.                                            AEEventID pAEEventID,
  168.                                            AppleEvent *pAppleEvent );
  169. /********************************************************************************
  170.     Create and return an AppleEvent of the given class and ID. The event will be
  171.     targeted with the provided TargetID.
  172.  
  173.     pTargetID        input:    Pointer to the TargetID to target the event with.
  174.     pAEEventClass    input:    The class of the event to be created.
  175.     pAEEventID        input:    The ID of the event to be created.
  176.     pAppleEvent        input:    Pointer to an AppleEvent where the
  177.                             event record will be returned.
  178.                     output:    The Apple event.
  179.     
  180.     RESULT CODES
  181.     ____________
  182.     noErr               0    No error    
  183.     memFullErr        -108    Not enough room in heap zone    
  184.     procNotFound    –600    No eligible process with specified descriptor
  185.     ____________
  186. */
  187. extern pascal OSErr    MoreAECreateAppleEventTargetID( const TargetID *pTargetID,
  188.                                       AEEventClass pAEEventClass,
  189.                                       AEEventID pAEEventID,
  190.                                       AppleEvent *pAppleEvent );
  191. /********************************************************************************
  192.     Send the provided AppleEvent using the provided idle function.
  193.     Will wait for a reply if an idle function is provided, but no result will be returned.
  194.  
  195.     pIdleProcUPP    input:    The idle function to use when sending the event.
  196.     pAppleEvent        input:    The event to be sent.
  197.     
  198.     RESULT CODES
  199.     ____________
  200.     noErr               0    No error    
  201.     
  202.     and any other error that can be returned by AESend or the handler
  203.     in the application that gets the event.
  204.     ____________
  205. */
  206. extern pascal OSErr    MoreAESendEventNoReturnValue( const AEIdleUPP pIdleProcUPP,
  207.                                            const AppleEvent *pAppleEvent );
  208. /********************************************************************************
  209.     Send the provided AppleEvent using the provided idle function.
  210.     Return data (at pDataPtr) of type pDesiredType
  211.  
  212.     pIdleProcUPP    input:    The idle function to use when sending the event.
  213.     pAppleEvent        input:    The event to be sent.
  214.     theValue        output:    The value returned by the event.
  215.  
  216.     RESULT CODES
  217.     ____________
  218.     noErr               0    No error    
  219.     paramErr         -50    No idle function provided
  220.  
  221.     and any other error that can be returned by AESend or the handler
  222.     in the application that gets the event.
  223.     ____________
  224. */
  225. extern pascal OSErr MoreAESendEventReturnData(
  226.                         const AEIdleUPP        pIdleProcUPP,
  227.                         const AppleEvent    *pAppleEvent,
  228.                         DescType            pDesiredType,
  229.                         DescType*            pActualType,
  230.                         void*                 pDataPtr,
  231.                         Size                pMaximumSize,
  232.                         Size                 *pActualSize);
  233. /********************************************************************************
  234.     Send the provided AppleEvent using the provided idle function.
  235.     Return a SInt16 (typeSmallInteger).
  236.  
  237.     pIdleProcUPP    input:    The idle function to use when sending the event.
  238.     pAppleEvent        input:    The event to be sent.
  239.     theValue        output:    The value returned by the event.
  240.     
  241.     RESULT CODES
  242.     ____________
  243.     noErr               0    No error    
  244.     paramErr         -50    No idle function provided
  245.     
  246.     and any other error that can be returned by AESend or the handler
  247.     in the application that gets the event.
  248.     ____________
  249. */
  250. extern pascal OSErr    MoreAESendEventReturnSInt16(
  251.                     const AEIdleUPP pIdleProcUPP,
  252.                     const AppleEvent *pAppleEvent,
  253.                     SInt16 *theValue );
  254. /********************************************************************************
  255.     Send the provided AppleEvent using the provided idle function.
  256.     Returns a PString.
  257.  
  258.     pIdleProcUPP    input:    The idle function to use when sending the event.
  259.     pAppleEvent        input:    The event to be sent.
  260.     pStr255        output:    The value returned by the event.
  261.  
  262.     RESULT CODES
  263.     ____________
  264.     noErr               0    No error    
  265.     paramErr         -50    No idle function provided
  266.  
  267.     and any other error that can be returned by AESend or the handler
  268.     in the application that gets the event.
  269.     ____________
  270. */
  271. extern pascal OSErr MoreAESendEventReturnPString(
  272.                         const AEIdleUPP pIdleProcUPP,
  273.                         const AppleEvent* pAppleEvent,
  274.                         Str255 pStr255);
  275. /********************************************************************************
  276.     Send an AppleEvent of the specified Class & ID to myself using the 
  277.     provided idle function.  The actual target of the event is the
  278.     pSelection property of the application.
  279.  
  280.     pIdleProcUPP    input:    The idle function to use when sending the event.
  281.     pEventID        input:    The event to be sent.
  282.  
  283.     RESULT CODES
  284.     ____________
  285.     noErr               0    No error    
  286.  
  287.     and any other error that can be returned by AESend or the handler
  288.     in the application that gets the event.
  289.     ____________
  290. */
  291. extern pascal OSErr MoreAESendToSelfNoReturnValue(
  292.                 const AEEventClass pEventClass,
  293.                 const AEEventID pEventID);
  294.  
  295. /********************************************************************************
  296.     Send an AppleEvent of the specified Class & ID to myself using the 
  297.     provided idle function. Wait for a reply and extract a SInt16 result.
  298.     The actual target of the event is the pSelection property of the 
  299.     application.
  300.  
  301.     pIdleProcUPP    input:    The idle function to use when sending the event.
  302.     pEventID        input:    The event to be sent.
  303.     pValue            Output:    Where the return SInt16 will be stored.
  304.  
  305.     RESULT CODES
  306.     ____________
  307.     noErr               0    No error    
  308.  
  309.     and any other error that can be returned by AESend or the handler
  310.     in the application that gets the event.
  311.     ____________
  312. */
  313. extern pascal OSErr MoreAESendToSelfReturnSInt16(
  314.                 const AEEventClass pEventClass,
  315.                 const AEEventID pEventID,
  316.                 SInt16* pValue);
  317.  
  318. /********************************************************************************
  319.     Send a get data (kAEGetData) AppleEvent to myself using the 
  320.     provided idle function. Wait for a reply and extract a SInt16 result.
  321.     
  322.     pIdleProcUPP    input:    The idle function to use when sending the event.
  323.     pEventID        input:    The event to be sent.
  324.     pValue            Output:    Where the resulting SInt16 will be stored.
  325.  
  326.     RESULT CODES
  327.     ____________
  328.     noErr               0    No error    
  329.  
  330.     and any other error that can be returned by AESend or the handler
  331.     in the application that gets the event.
  332.     ____________
  333. */
  334. extern pascal OSErr MoreAETellSelfToGetSInt16Property(
  335.                 const DescType pPropType,
  336.                 SInt16* pValue);
  337.  
  338. /********************************************************************************
  339.     Send a get data (kAEGetData) AppleEvent to myself using the 
  340.     provided idle function. Wait for a reply and extract a Str255 result.
  341.     The actual target of the event is the pSelection property of the 
  342.     application.
  343.  
  344.     pIdleProcUPP    input:    The idle function to use when sending the event.
  345.     pEventID        input:    The event to be sent.
  346.     pValue            Output:    Where the resulting Str255 will be stored.
  347.  
  348.     RESULT CODES
  349.     ____________
  350.     noErr               0    No error    
  351.  
  352.     and any other error that can be returned by AESend or the handler
  353.     in the application that gets the event.
  354.     ____________
  355. */
  356. extern pascal OSErr MoreAETellSelfToGetStr255Property(
  357.                 const DescType pPropType,
  358.                 Str255 pValue);
  359.  
  360. /********************************************************************************
  361.     Send a set data (kAESetData) AppleEvent to myself with a SInt16 parameter
  362.     and using the provided idle function.
  363.  
  364.     pIdleProcUPP    input:    The idle function to use when sending the event.
  365.     pEventID        input:    The event to be sent.
  366.     pValue            Output:    Where the resulting SInt16 will be stored.
  367.  
  368.     RESULT CODES
  369.     ____________
  370.     noErr               0    No error    
  371.  
  372.     and any other error that can be returned by AESend or the handler
  373.     in the application that gets the event.
  374.     ____________
  375. */
  376. extern pascal OSErr MoreAETellSelfToSetSInt16Property(
  377.                 const DescType pPropType,
  378.                 SInt16 pValue);
  379.  
  380. /********************************************************************************
  381.     Send a set data (kAESetData) AppleEvent to myself with a SInt16 parameter
  382.     and using the provided idle function.
  383.  
  384.     pIdleProcUPP    input:    The idle function to use when sending the event.
  385.     pEventID        input:    The event to be sent.
  386.     pValue            Output:    Where the resulting Str255 will be stored.
  387.  
  388.     RESULT CODES
  389.     ____________
  390.     noErr               0    No error    
  391.  
  392.     and any other error that can be returned by AESend or the handler
  393.     in the application that gets the event.
  394.     ____________
  395. */
  396. extern pascal OSErr MoreAETellSelfToSetStr255Property(
  397.                 const DescType pPropType,
  398.                 Str255 pValue);
  399.  
  400. //*******************************************************************************
  401. // Appends each of the items in pSourceList to the pDestList.
  402. extern pascal OSStatus MoreAEAppendListToList(const AEDescList *pSourceList, AEDescList *pDestList);
  403.  
  404. //*******************************************************************************
  405. // This routine takes a result descriptor and an error.
  406. // If there is a result to add to the reply it makes sure the reply isn't
  407. // NULL itself then adds the error to the reply depending on the error
  408. // and the type of result.
  409. extern pascal OSErr MoreAEMoreAESetReplyErrorNumber (OSErr pOSErr, AppleEvent *pAEReply);
  410. //*******************************************************************************
  411. // This routine takes a result descriptor, a reply descriptor and an error.
  412. // If there is a result to add to the reply it makes sure the reply isn't
  413. // NULL itself then adds the result to the reply depending on the error
  414. // and the type of result.
  415. extern pascal OSErr MoreAEAddResultToReply(AEDesc* pResult, AEDesc* pAEReply, OSErr error);
  416. // ----------------------------------------------------------------------
  417. //    Name:        MoreAEGotRequiredParams
  418. //    Function:    Checks that all parameters defined as 'required' have been read
  419. // ----------------------------------------------------------------------
  420. extern pascal OSErr    MoreAEGotRequiredParams(const AppleEvent *theAppleEvent);
  421. /********************************************************************************
  422.     Takes a reply event checks it for any errors that may have been returned
  423.     by the event handler. A simple function, in that it only returns the error
  424.     number. You can often also extract an error string and three other error
  425.     parameters from a reply event.
  426.     
  427.     Also see:
  428.         IM:IAC for details about returned error strings.
  429.         AppleScript developer release notes for info on the other error parameters.
  430.     
  431.     pAEReply        input:    The reply event to be checked.
  432.  
  433.     RESULT CODES
  434.     ____________
  435.     noErr                    0    No error    
  436.     ????                    ??    Pretty much any error, depending on what the
  437.                                 event handler returns for it's errors.
  438. */
  439. extern pascal OSErr    MoreAEGetHandlerError( const AppleEvent *pAEReply );
  440. /********************************************************************************
  441.     Get the class and ID from an AppleEvent.
  442.  
  443.     pAppleEvent        input:    The event to get the class and ID from.
  444.     pAEEventClass       output:    The event's class.
  445.     pAEEventID           output:    The event's ID.
  446.     
  447.     RESULT CODES
  448.     ____________
  449.     noErr                        0    No error    
  450.     memFullErr                 -108    Not enough room in heap zone    
  451.     errAEDescNotFound         -1701    Descriptor record was not found    
  452.     errAENotAEDesc            -1704    Not a valid descriptor record    
  453.     errAEReplyNotArrived    -1718    Reply has not yet arrived    
  454. */    
  455. extern pascal OSErr MoreAEExtractClassAndID ( const AppleEvent *pAppleEvent,
  456.                              AEEventClass *pAEEventClass,
  457.                              AEEventID *pAEEventID );
  458. /********************************************************************************
  459.     A very simple idle function. It simply ignors any event it receives,
  460.     returns 30 for the sleep time and nil for the mouse region.
  461.     
  462.     Your application should supply an idle function that handles any events it
  463.     might receive. This is especially important if your application has any windows.
  464.     
  465.     Also see:
  466.         IM:IAC for details about idle functions.
  467.         Pending Update Perils technote for more about handling low-level events.
  468. */    
  469. extern pascal Boolean    MoreAESimpleIdleFunction( EventRecord *event,
  470.                                        long *sleepTime,
  471.                                        RgnHandle *mouseRgn );
  472. /********************************************************************************
  473.     Is the Apple Event Manager present.
  474.     
  475.     RESULT CODES
  476.     ____________
  477.     true    The Apple Event Manager is present
  478.     false    It isn't
  479. */
  480. extern pascal Boolean    MoreAEHasAppleEvents(void);
  481. //*******************************************************************************
  482. // Did this AppleEvent come from the Finder?
  483. extern pascal OSErr MoreAEIsSenderFinder (const AppleEvent *pAppleEvent, Boolean *pIsFinder);
  484.  
  485. //*******************************************************************************
  486. // Initialises desc to the null descriptor (typeNull, nil).
  487. extern pascal void MoreAENullDesc(AEDesc *desc);
  488. //*******************************************************************************
  489. // Disposes of desc and initialises it to the null descriptor.
  490. extern pascal void MoreAEDisposeDesc(AEDesc *desc);
  491. //*******************************************************************************
  492. // These routines are only implemented in PreCarbon.o for PowerPC
  493. // So for 68K we had to write our own versions
  494. #if TARGET_CPU_68K || !ACCESSOR_CALLS_ARE_FUNCTIONS
  495. extern pascal Size AEGetDescDataSize( const AEDesc* pAEDesc);
  496. extern pascal OSErr AEGetDescData(
  497.                     const AEDesc*    pAEDesc,
  498.                     void*            pDataPtr,
  499.                     Size             pMaxSize);
  500. #endif TARGET_CPU_68K || !ACCESSOR_CALLS_ARE_FUNCTIONS
  501. /********************************************************************************
  502.     These are generic routines that are used to extract data of
  503.     different types from descriptor records.
  504.  
  505.     pAEDesc            input:    The descriptor we want the data from
  506.     pDestPtr        output:    Where we want to store the data from this desc.
  507.     pMaxSize        input:    The maxium amount of data we can store.
  508.     pActualSize        output:    The actual amount of data stored.
  509.  
  510.     RESULT CODES
  511.     ____________
  512.     noErr               0    No error    
  513.     ____________
  514. */
  515. extern pascal void MoreAEGetRawDataFromDescriptor(const AEDesc* pAEDesc,
  516.                              Ptr     pDestPtr,
  517.                              Size    pMaxSize,
  518.                              Size    *pActualSize);
  519. extern pascal OSErr MoreAEGetPStringFromDescriptor(const AEDesc* pAEDesc, StringPtr pStringPtr);
  520. extern pascal OSErr MoreAEGetCStringFromDescriptor(const AEDesc* pAEDesc, char* pCharPtr);
  521. extern pascal OSErr MoreAEGetShortFromDescriptor(const AEDesc* pAEDesc, SInt16 *pResult);
  522. extern pascal OSErr MoreAEGetBooleanFromDescriptor(const AEDesc* pAEDesc,Boolean *pResult);
  523. extern pascal OSErr MoreAEGetLongFromDescriptor(const AEDesc* pAEDesc, long   *pResult);
  524. extern pascal OSErr MoreAEGetOSTypeFromDescriptor(const AEDesc* pAEDesc, OSType   *pResult);
  525.  
  526. //*******************************************************************************
  527. // This routine creates a new handle and puts the contents of the desc
  528. // in that handle.  Carbon’s opaque AEDesc’s means that we need this
  529. // functionality a lot.
  530.  
  531. extern pascal OSStatus MoreAECopyDescriptorDataToHandle(const AEDesc *desc, Handle *descData);
  532.  
  533. //*******************************************************************************
  534. // This routine returns true if and only if desc is the "missing value" value.
  535.  
  536. extern pascal Boolean MoreAEIsMissingValue(const AEDesc *desc);
  537.  
  538. //*******************************************************************************
  539. // This routine creates a descriptor that represents the missing value.
  540.  
  541. extern pascal OSStatus MoreAECreateMissingValue(AEDesc *desc);
  542.  
  543. #ifdef __cplusplus
  544. }
  545. #endif
  546.